OpenEuphoria

for_each

include map.e 
namespace map 
public function for_each(map source_map, integer user_rid, object user_data = 0, 
        integer in_sorted_order = 0, integer signal_boundary = 0) 

calls a user-defined routine for each of the items in a map.

Parameters:

1. source_map : The map containing the data to process
2. user_rid: The routine_id of a user defined processing function
3. user_data: An object. Optional. This is passed, unchanged to each call of the user defined routine. By default, zero (0) is used.
4. in_sorted_order: An integer. Optional. If non-zero the items in the map are processed in ascending key sequence otherwise the order is undefined. By default they are not sorted.
5. signal_boundary: A integer; 0 (the default) means that the user routine is not called if the map is empty and when the last item is passed to the user routine, the Progress Code is not negative.

Returns:

An integer: 0 means that all the items were processed, and anything else is whatever was returned by the user routine to abort the for_each process.

Comments:

• The user defined routine is a function that must accept four parameters.
  1. Object: an Item Key
  2. Object: an Item Value
  3. Object: The user_data value. This is never used by for_each itself, merely passed to the user routine.
  4. Integer: Progress code.
     • The abs value of the progress code is the ordinal call number. That is 1 means the first call, 2 means the second call, etc ...
     • If the progress code is negative, it is also the last call to the routine.
     • If the progress code is zero, it means that the map is empty and thus the item key and value cannot be used.
     • note that if signal_boundary is zero, the Progress Code is never less than 1.
• The user routine must return 0 to get the next map item. Anything else will cause for_each to stop running, and is returned to whatever called for_each.
• Note that any changes that the user routine makes to the map do not affect the order or number of times the routine is called. for_each takes a copy of the map keys and data before the first call to the user routine and uses the copied data to call the user routine.

Example 1:

include std/map.e 
include std/math.e 
include std/io.e 
 
function Process_A(object k, object v, object d, integer pc) 
    writefln("[] = []", {k, v}) 
    return 0 
end function 
 
function Process_B(object k, object v, object d, integer pc) 
    if pc = 0 then 
      writefln("The map is empty") 
    else 
      integer c 
      c = abs(pc) 
      if c = 1 then 
          writefln("---[]---", {d}) -- Write the report title. 
      end if 
      writefln("[]: [:15] = []", {c, k, v}) 
      if pc < 0 then 
          writefln(repeat('-', length(d) + 6), {}) -- Write the report end. 
      end if 
    end if 
    return 0 
end function 
 
map m1 = new() 
map:put(m1, "application", "Euphoria") 
map:put(m1, "version", "4.0") 
map:put(m1, "genre", "programming language") 
map:put(m1, "crc", "4F71AE10") 
 
-- Unsorted  
map:for_each(m1, routine_id("Process_A")) 
-- Sorted 
map:for_each(m1, routine_id("Process_B"), "List of Items", 1)   

The output from the first call could be...

application = Euphoria 
version = 4.0 
genre = programming language 
crc = 4F71AE10 

The output from the second call should be...

---List of Items--- 
1: application     = Euphoria 
2: crc             = 4F71AE10 
3: genre           = programming language 
4: version         = 4.0 
-------------------